OpenSea Analytics Agent Tool

{
  "id": "yRMCUm6oJEMknhbw",
  "meta": {
    "instanceId": "a5283507e1917a33cc3ae615b2e7d5ad2c1e50955e6f831272ddd5ab816f3fb6"
  },
  "name": "OpenSea Analytics Agent Tool",
  "tags": [],
  "nodes": [
    {
      "id": "9478ead9-7f35-49b5-aff7-401ce9b8f4af",
      "name": "Analytics Agent Brain",
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "position": [
        300,
        40
      ],
      "parameters": {
        "model": {
          "__rl": true,
          "mode": "list",
          "value": "gpt-4o-mini"
        },
        "options": {}
      },
      "credentials": {
        "openAiApi": {
          "id": "yUizd8t0sD5wMYVG",
          "name": "OpenAi account"
        }
      },
      "typeVersion": 1.2
    },
    {
      "id": "80910bd9-7889-4185-8cfd-31a6aca270ff",
      "name": "Analytics Agent Memory",
      "type": "@n8n/n8n-nodes-langchain.memoryBufferWindow",
      "position": [
        440,
        40
      ],
      "parameters": {},
      "typeVersion": 1.3
    },
    {
      "id": "b810757e-caa3-4987-be0a-66284e01d6b9",
      "name": "OpenSea Get Collection Stats",
      "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
      "position": [
        600,
        40
      ],
      "parameters": {
        "url": "https://api.opensea.io/api/v2/collections/{collection_slug}/stats",
        "sendHeaders": true,
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "toolDescription": "This tool retrieves statistics for a single NFT collection from OpenSea by collection slug.",
        "parametersHeaders": {
          "values": [
            {
              "name": "Accept",
              "value": "application/json",
              "valueProvider": "fieldValue"
            }
          ]
        }
      },
      "credentials": {
        "httpHeaderAuth": {
          "id": "3v99GVMGF4tKP5nM",
          "name": "OpenSea"
        }
      },
      "typeVersion": 1.1
    },
    {
      "id": "288220ab-4321-4916-8ea1-bd27495b3b57",
      "name": "OpenSea Analytics Agent",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "position": [
        600,
        -200
      ],
      "parameters": {
        "text": "={{ $json.message }}",
        "options": {
          "systemMessage": "# **📢 OpenSea Analytics Agent – System Message**  

## **🔹 Role & Purpose**
The **OpenSea Analytics Agent** is an advanced **AI-powered NFT data analyst** with direct access to **OpenSea’s API**. It specializes in **retrieving and analyzing NFT market data**, including:
- Collection statistics (sales volume, floor prices, market cap, etc.)
- Transaction histories (sales, bids, transfers, listings)
- Event tracking for specific wallets, collections, and NFTs  
- Market trends & price movements  

This agent **ensures all API calls follow OpenSea’s exact requirements**, preventing invalid queries and ensuring fast, accurate responses.  

---

## **⚡ Available Tools & How to Use Them**
The **Analytics Agent** integrates multiple **OpenSea API endpoints** to retrieve, process, and analyze NFT data.

### **1️⃣ OpenSea Get Collection Stats**
📍 **Endpoint**: `/api/v2/collections/{collection_slug}/stats`  
🔹 **Description**: Retrieves **key statistics** for a specific NFT collection, including:
  - Total sales volume (ETH)  
  - Number of sales  
  - Average price  
  - Market cap  
  - Number of owners  
  - Floor price  

🔹 **Required Parameter**:  
  - `collection_slug` → The unique identifier of the NFT collection on OpenSea  

🔹 **Example Query**:  
  _\"Get stats for the Bored Ape Yacht Club collection.\"_  

✅ **API Call Example:**  
```plaintext
GET https://api.opensea.io/api/v2/collections/boredapeyachtclub/stats
```  

---

### **2️⃣ OpenSea Get Events**
📍 **Endpoint**: `/api/v2/events`  
🔹 **Description**: Retrieves **NFT-related events** (sales, transfers, listings, bids, and redemptions) that occurred within a specific timeframe.  

🔹 **Optional Query Parameters:**  
  - `after` → Fetch events occurring after this Unix timestamp.  
  - `before` → Fetch events occurring before this Unix timestamp.  
  - `event_type` → Filter by event types (`sale`, `transfer`, `redemption`).  
  - `limit` → Number of results (1-50, default: 50).  
  - `next` → Cursor for pagination.  

🔹 **Example Query**:  
  _\"Show me all NFT sales from the last 24 hours.\"_  

✅ **API Call Example:**  
```plaintext
GET https://api.opensea.io/api/v2/events?event_type=sale&after=1710960000
```  

---

### **3️⃣ OpenSea Get Events (by Account)**
📍 **Endpoint**: `/api/v2/events/accounts/{address}`  
🔹 **Description**: Retrieves **all events related to a specific wallet address**.  

🔹 **Required Parameter**:  
  - `address` → Wallet address of interest  

🔹 **Optional Parameters:**  
  - `chain` → Blockchain network (**must be valid, see list below**).  
  - `event_type` → Filter events (`sale`, `transfer`, `redemption`).  
  - `limit` → Number of results (1-50, default: 50).  
  - `next` → Cursor for pagination.  

🔹 **Example Query**:  
  _\"Fetch all NFT transfers for wallet `0x123...abc` on Ethereum.\"_  

✅ **API Call Example:**  
```plaintext
GET https://api.opensea.io/api/v2/events/accounts/0x123...abc?event_type=transfer&chain=ethereum
```  

---

### **4️⃣ OpenSea Get Events (by Collection)**
📍 **Endpoint**: `/api/v2/events/collection/{collection_slug}`  
🔹 **Description**: Retrieves **all NFT events related to a specific collection**.  

🔹 **Required Parameter**:  
  - `collection_slug` → The unique identifier of the NFT collection  

🔹 **Example Query**:  
  _\"Get the latest 10 sales for Azuki NFTs.\"_  

✅ **API Call Example:**  
```plaintext
GET https://api.opensea.io/api/v2/events/collection/azuki?event_type=sale&limit=10
```  

---

### **5️⃣ OpenSea Get Events (by NFT)**
📍 **Endpoint**: `/api/v2/events/chain/{chain}/contract/{address}/nfts/{identifier}`  
🔹 **Description**: Retrieves **all historical events for a specific NFT** based on:
  - **Blockchain**  
  - **Smart contract address**  
  - **Token ID**  

🔹 **Required Parameters**:  
  - `chain` → Blockchain network (**must be valid, see list below**).  
  - `address` → Smart contract address of the NFT.  
  - `identifier` → Unique NFT token ID.  

🔹 **Example Query**:  
  _\"Show me the last 5 transactions for CryptoPunk #9999.\"_  

✅ **API Call Example:**  
```plaintext
GET https://api.opensea.io/api/v2/events/chain/ethereum/contract/0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB/nfts/9999?limit=5
```  

---

## **⚠️ Important Rules & Restrictions**
### **🚨 1. Only Allowed Blockchain Inputs**
✅ **Valid Blockchains for Queries**:
- `amoy`
- `ape_chain`
- `ape_curtis`
- `arbitrum`
- `arbitrum_nova`
- `arbitrum_sepolia`
- `avalanche`
- `avalanche_fuji`
- `b3`
- `b3_sepolia`
- `baobab`
- `base`
- `base_sepolia`
- `bera_chain`
- `blast`
- `blast_sepolia`
- `ethereum`
- `flow`
- `flow_testnet`
- `klaytn`
- **`matic`** _(Use this instead of \"polygon\")_
- `monad_testnet`
- `mumbai`
- `optimism`
- `optimism_sepolia`
- `sei_testnet`
- `sepolia`
- `shape`
- `solana`
- `soldev`
- `soneium`
- `soneium_minato`
- `unichain`
- `zora`
- `zora_sepolia`

🚨 **Critical Rule:**
- ❌ `\"polygon\"` **is NOT a valid chain input** and **must be replaced with** `\"matic\"`.  
- ❌ Using an unsupported blockchain **will cause an error**.  
- ✅ Always verify blockchain names before executing a query.

---

## **📌 Example Queries**
✅ _\"Get NFT sales data for the past 7 days.\"_  
✅ _\"Fetch the top 5 trending collections by volume.\"_  
✅ _\"Track all NFT transactions for my wallet `0xabc...xyz`.\"_  
✅ _\"Show me the most expensive sale in the last 24 hours.\"_  

---

## **⚠️ Error Handling**
If an OpenSea API request fails, **check for errors**:
- ✅ `200` → Success  
- ❌ `400` → Bad Request (Invalid input format)  
- ❌ `404` → Not Found (Incorrect `collection_slug`, `address`, or `identifier`)  
- ❌ `500` → Server Error (OpenSea API issue)  

---

# **🚀 Conclusion**
The **OpenSea Analytics Agent** is a specialized **AI-driven NFT analyst** designed to track market trends, analyze transactions, and provide **real-time NFT insights**. Whether you're a **trader, investor, or collector**, this system ensures you stay ahead of the market with **accurate, structured, and powerful NFT analytics**.  

🔥 **Follow all rules to ensure successful API queries!** 🔥"
        },
        "promptType": "define"
      },
      "typeVersion": 1.8
    },
    {
      "id": "c055762a-8fe7-4141-a639-df2372f30060",
      "name": "Workflow Input Trigger",
      "type": "n8n-nodes-base.executeWorkflowTrigger",
      "position": [
        140,
        -200
      ],
      "parameters": {
        "workflowInputs": {
          "values": [
            {
              "name": "message"
            },
            {
              "name": "sessionId"
            }
          ]
        }
      },
      "typeVersion": 1.1
    },
    {
      "id": "ea5f7259-ff8b-48bc-9bde-01b7d2d42d2b",
      "name": "OpenSea Get Events",
      "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
      "position": [
        780,
        40
      ],
      "parameters": {
        "url": "https://api.opensea.io/api/v2/events",
        "sendQuery": true,
        "sendHeaders": true,
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "parametersQuery": {
          "values": [
            {
              "name": "event_type",
              "valueProvider": "modelOptional"
            },
            {
              "name": "after",
              "valueProvider": "modelOptional"
            },
            {
              "name": "before",
              "valueProvider": "modelOptional"
            },
            {
              "name": "limit",
              "valueProvider": "modelOptional"
            },
            {
              "name": "next",
              "valueProvider": "modelOptional"
            }
          ]
        },
        "toolDescription": "This tool retrieves a list of OpenSea events based on timestamps, event type, and pagination.",
        "parametersHeaders": {
          "values": [
            {
              "name": "Accept",
              "value": "application/json",
              "valueProvider": "fieldValue"
            }
          ]
        }
      },
      "credentials": {
        "httpHeaderAuth": {
          "id": "3v99GVMGF4tKP5nM",
          "name": "OpenSea"
        }
      },
      "typeVersion": 1.1
    },
    {
      "id": "d18c5b15-bc5d-4053-8364-9ecedc36483a",
      "name": "OpenSea Get Events by Account",
      "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
      "position": [
        960,
        40
      ],
      "parameters": {
        "url": "https://api.opensea.io/api/v2/events/accounts/{address}",
        "sendQuery": true,
        "sendHeaders": true,
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "parametersQuery": {
          "values": [
            {
              "name": "after",
              "valueProvider": "modelOptional"
            },
            {
              "name": "before",
              "valueProvider": "modelOptional"
            },
            {
              "name": "chain",
              "valueProvider": "modelOptional"
            },
            {
              "name": "event_type",
              "valueProvider": "modelOptional"
            },
            {
              "name": "limit",
              "valueProvider": "modelOptional"
            },
            {
              "name": "next",
              "valueProvider": "modelOptional"
            }
          ]
        },
        "toolDescription": "This tool retrieves a list of OpenSea events for a specific account based on timestamps, chain, event type, and pagination.",
        "parametersHeaders": {
          "values": [
            {
              "name": "Accept",
              "value": "application/json",
              "valueProvider": "fieldValue"
            }
          ]
        }
      },
      "credentials": {
        "httpHeaderAuth": {
          "id": "3v99GVMGF4tKP5nM",
          "name": "OpenSea"
        }
      },
      "typeVersion": 1.1
    },
    {
      "id": "74b00939-5c0f-4974-8d6e-35cfb9dc5c79",
      "name": "OpenSea Get Events by Collection",
      "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
      "position": [
        1160,
        40
      ],
      "parameters": {
        "url": "https://api.opensea.io/api/v2/events/collection/{collection_slug}",
        "sendQuery": true,
        "sendHeaders": true,
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "parametersQuery": {
          "values": [
            {
              "name": "after",
              "valueProvider": "modelOptional"
            },
            {
              "name": "before",
              "valueProvider": "modelOptional"
            },
            {
              "name": "event_type",
              "valueProvider": "modelOptional"
            },
            {
              "name": "limit",
              "valueProvider": "modelOptional"
            },
            {
              "name": "next",
              "valueProvider": "modelOptional"
            }
          ]
        },
        "toolDescription": "This tool retrieves a list of OpenSea events for a specific collection based on timestamps, event type, and pagination.",
        "parametersHeaders": {
          "values": [
            {
              "name": "Accept",
              "value": "application/json",
              "valueProvider": "fieldValue"
            }
          ]
        }
      },
      "credentials": {
        "httpHeaderAuth": {
          "id": "3v99GVMGF4tKP5nM",
          "name": "OpenSea"
        }
      },
      "typeVersion": 1.1
    },
    {
      "id": "79af849c-af1b-40a2-861f-91c6217c7a99",
      "name": "OpenSea Get Events by NFT",
      "type": "@n8n/n8n-nodes-langchain.toolHttpRequest",
      "position": [
        1360,
        40
      ],
      "parameters": {
        "url": "https://api.opensea.io/api/v2/events/chain/{chain}/contract/{address}/nfts/{identifier}",
        "sendQuery": true,
        "sendHeaders": true,
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "parametersQuery": {
          "values": [
            {
              "name": "after",
              "valueProvider": "modelOptional"
            },
            {
              "name": "before",
              "valueProvider": "modelOptional"
            },
            {
              "name": "event_type",
              "valueProvider": "modelOptional"
            },
            {
              "name": "limit",
              "valueProvider": "modelOptional"
            },
            {
              "name": "next",
              "valueProvider": "modelOptional"
            }
          ]
        },
        "toolDescription": "This tool retrieves a list of OpenSea events for a single NFT based on chain, contract address, token ID, timestamps, and event type.",
        "parametersHeaders": {
          "values": [
            {
              "name": "Accept",
              "value": "application/json",
              "valueProvider": "fieldValue"
            }
          ]
        }
      },
      "credentials": {
        "httpHeaderAuth": {
          "id": "3v99GVMGF4tKP5nM",
          "name": "OpenSea"
        }
      },
      "typeVersion": 1.1
    },
    {
      "id": "c268e4cc-2a31-4d0d-b155-bf38c8bb8840",
      "name": "Sticky Note",
      "type": "n8n-nodes-base.stickyNote",
      "position": [
        -1260,
        -1260
      ],
      "parameters": {
        "color": 2,
        "width": 980,
        "height": 1320,
        "content": "# OpenSea Analytics Agent Tool (n8n Workflow) Guide

## 🚀 Workflow Overview
The **OpenSea Analytics Agent Tool** is an AI-powered NFT analytics system built using **n8n**. It integrates directly with **OpenSea's API** to fetch and analyze market data, collection stats, wallet transactions, and event logs. This tool is designed to provide real-time insights into the NFT ecosystem.

### 🎯 **Key Features**:
- Retrieve **collection statistics** (volume, floor price, market cap, etc.).
- Track **NFT events** (sales, transfers, listings, bids, redemptions).
- Monitor **wallet transactions** (account-specific event tracking).
- Fetch **NFT-specific historical transactions** by smart contract and token ID.
- Ensure **API compliance**, preventing invalid queries and errors.

---

## 🔗 **Nodes & Functions**
Below is a breakdown of each node in the workflow and its function.

### **1️⃣ Analytics Agent Brain**
- **Type**: AI Language Model (GPT-4o Mini)
- **Purpose**: Processes API requests and interprets OpenSea analytics queries.

### **2️⃣ Analytics Agent Memory**
- **Type**: AI Memory Buffer
- **Purpose**: Stores session data to maintain context for multiple queries.

### **3️⃣ OpenSea Get Collection Stats**
- **Type**: API Request
- **Endpoint**: `/api/v2/collections/{collection_slug}/stats`
- **Function**: Fetches collection-wide statistics such as floor price, total volume, number of sales, and market cap.

### **4️⃣ OpenSea Get Events**
- **Type**: API Request
- **Endpoint**: `/api/v2/events`
- **Function**: Retrieves NFT-related events within a given timeframe, filtered by event type (sale, transfer, listing, etc.).

### **5️⃣ OpenSea Get Events by Account**
- **Type**: API Request
- **Endpoint**: `/api/v2/events/accounts/{address}`
- **Function**: Tracks all NFT events related to a specific wallet address.

### **6️⃣ OpenSea Get Events by Collection**
- **Type**: API Request
- **Endpoint**: `/api/v2/events/collection/{collection_slug}`
- **Function**: Fetches the latest events for a particular NFT collection.

### **7️⃣ OpenSea Get Events by NFT**
- **Type**: API Request
- **Endpoint**: `/api/v2/events/chain/{chain}/contract/{address}/nfts/{identifier}`
- **Function**: Retrieves all historical events for a single NFT based on blockchain, smart contract, and token ID.

---

"
      },
      "typeVersion": 1
    },
    {
      "id": "ef15cdff-2e09-4ae9-8c7f-a01119020a29",
      "name": "Sticky Note1",
      "type": "n8n-nodes-base.stickyNote",
      "position": [
        -160,
        -1260
      ],
      "parameters": {
        "color": 5,
        "width": 920,
        "height": 940,
        "content": "## 📌 **How to Use the Workflow**

### ✅ **Step 1: Input Data**
- Provide the necessary parameters like `collection_slug`, `address`, `event_type`, `chain`, and `identifier`.

### ✅ **Step 2: API Calls Execution**
- The workflow triggers API calls based on the input and retrieves structured NFT analytics data.

### ✅ **Step 3: Data Processing & Output**
- The AI-powered agent processes responses and formats the output.
- Results can be sent to Telegram, saved in a database, or displayed in a dashboard.

---

## ⚠️ **Common API Queries & Examples**

### **1️⃣ Get Collection Stats**
```plaintext
GET https://api.opensea.io/api/v2/collections/boredapeyachtclub/stats
```

### **2️⃣ Get Events (Last 24 Hours NFT Sales)**
```plaintext
GET https://api.opensea.io/api/v2/events?event_type=sale&after=1710960000
```

### **3️⃣ Get Events by Wallet Address**
```plaintext
GET https://api.opensea.io/api/v2/events/accounts/0x123...abc?event_type=transfer&chain=ethereum
```

### **4️⃣ Get Events by NFT**
```plaintext
GET https://api.opensea.io/api/v2/events/chain/ethereum/contract/0xb47e3cd837dDF8e4c57F05d70Ab865de6e193BBB/nfts/9999?limit=5
```

---

"
      },
      "typeVersion": 1
    },
    {
      "id": "03ec28f4-c2bc-4cfe-a799-c0ad5190d77a",
      "name": "Sticky Note2",
      "type": "n8n-nodes-base.stickyNote",
      "position": [
        960,
        -1260
      ],
      "parameters": {
        "color": 3,
        "width": 820,
        "height": 460,
        "content": "## ⚡ **Error Handling & Troubleshooting**
| **Error Code** | **Description** |
|--------------|----------------|
| `200` | Success |
| `400` | Bad Request (Invalid input) |
| `404` | Not Found (Incorrect slug, address, or identifier) |
| `500` | Server Error (OpenSea API issue) |

### 🔹 **Fixing Common Errors**
- Ensure correct `collection_slug` or `wallet address` is provided.
- Check if the blockchain name is valid (`matic` instead of `polygon`).
- If the OpenSea API is down, retry after some time.

---

## 🚀 **Connect with Me for Support**
If you need assistance, custom OpenSea insights, or automation support, feel free to connect with me on LinkedIn:

🌐 **Don Jayamaha – LinkedIn**  
🔗 [http://linkedin.com/in/donjayamahajr](http://linkedin.com/in/donjayamahajr)

"
      },
      "typeVersion": 1
    }
  ],
  "active": false,
  "pinData": {},
  "settings": {
    "executionOrder": "v1"
  },
  "versionId": "59a62d76-59a4-4615-a546-6e3810ca81f2",
  "connections": {
    "OpenSea Get Events": {
      "ai_tool": [
        [
          {
            "node": "OpenSea Analytics Agent",
            "type": "ai_tool",
            "index": 0
          }
        ]
      ]
    },
    "Analytics Agent Brain": {
      "ai_languageModel": [
        [
          {
            "node": "OpenSea Analytics Agent",
            "type": "ai_languageModel",
            "index": 0
          }
        ]
      ]
    },
    "Analytics Agent Memory": {
      "ai_memory": [
        [
          {
            "node": "OpenSea Analytics Agent",
            "type": "ai_memory",
            "index": 0
          }
        ]
      ]
    },
    "Workflow Input Trigger": {
      "main": [
        [
          {
            "node": "OpenSea Analytics Agent",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "OpenSea Get Events by NFT": {
      "ai_tool": [
        [
          {
            "node": "OpenSea Analytics Agent",
            "type": "ai_tool",
            "index": 0
          }
        ]
      ]
    },
    "OpenSea Get Collection Stats": {
      "ai_tool": [
        [
          {
            "node": "OpenSea Analytics Agent",
            "type": "ai_tool",
            "index": 0
          }
        ]
      ]
    },
    "OpenSea Get Events by Account": {
      "ai_tool": [
        [
          {
            "node": "OpenSea Analytics Agent",
            "type": "ai_tool",
            "index": 0
          }
        ]
      ]
    },
    "OpenSea Get Events by Collection": {
      "ai_tool": [
        [
          {
            "node": "OpenSea Analytics Agent",
            "type": "ai_tool",
            "index": 0
          }
        ]
      ]
    }
  }
}